techdoc-ja 日本語で技術ドキュメントを記述する環境整備

都元ダイスケ

2017.12.22

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

よく訓練されたアップル信者、都元です。弊社は本日を最終営業日として、これから冬季休業となります。今年も一年、どうもありがとうございました。というわけで書き納めの一本、その3。

最近ドキュメントを書く機会が増えてきました。

仕様書は Markdown で書きたいですね。そして GitHub を使って書き進めたいですね。
PlantUML で簡単に作図ができるといいですね。図中では日本語も使いたいですよね。
さらに機械的に実行できる校正は、自動チェックしたいですね。
書き上がったものは自動的に HTML や PDF にして、S3 にデプロイしたいですね。
という一連のジョブは CI で実行したいですね。

という思いを実現するための環境を整えたので、ひとまず公開します。

どうやって実現するか

GitHub で Markdown は、まぁ単に書けって話ですよね。書いたコンテンツは gitbook を使ってビルドします。このあたりは以前も当ブログで紹介しているとおりです。

GitBook 環境を準備してみる

PlantUML による作図は gitbook-plugin-uml を使って実現します。ただし、ビルド環境に graphviz が必須となります。また、図中に日本語を使いたいとなると、フォントを考慮しておく必要があります。ライセンスと個人的な趣味から MigMix フォントを利用することにしました。

この文法で Markdown の中に書いた UML は、残念ながら GitHub 上でプレビューできず、ただのコードブロックとして表示されてしまいます。しかし、下記の Chrome 拡張を利用するとそのままプレビューできます。

GitHub 上で PlantUML をレンダリングするChrome拡張 v1.2.0 をリリースしました

gitbook は PDF を出力する機能を持っていますが、その場合はビルド環境に Calibre が必須となります。また、作図と同じようにフォントの考慮も必要になります。

S3 への自動デプロイは aws-cli で sync すればいいですね。そして CI には Circle CI 2.0 を利用することにしました。

必要なソフトウェアと Docker イメージ

必要なものをまとめると、意外と多いですね。これらをすべて、Circle CI 上から使うための Docker イメージを用意しました。

Docker としては、それぞれのイメージを用意するのが本来あるべき姿ではありますが、今回は単一のイメージですべてを実行できることを目指しました。

という Docker イメージが DockerHub classmethod/techdoc-ja です。 Dockerfile は GitHub classmethod/techdoc-ja に上げてありますので、何かありましたら issue/PR ください。

サンプルプロジェクト

GitHub classmethod/techdoc-ja-example にサンプルプロジェクトを用意しました。

このプロジェクトは Circle CI のビルドを設定済みで、最後に S3 バケットへ成果物をデプロイします。

HTML
PDF

また、校正に引っかかる PR も用意してみました。想定どおり CI が落ちていますね。

section4.md:34: ValidationError[JapaneseAmbiguousNounConjunction], 助詞「の」が連続しています: "〜システムの内容の詳細〜" at line: 本システムの内容の詳細は、以下の通りである。

また、RedPen が指摘する助詞の連続を修正しても textlint にはこのように指摘されます。

/root/workspace/content/section4.md
  34:14  ✓ error  以下の => 次の  prh
  34:17  ✓ error  通り => とおり  prh

✖ 2 problems (2 errors, 0 warnings)
✓ 2 fixable problems.